home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / C / GCC / V2-4-5 / GCCEXT / Virtual / !Virtual / !Help < prev    next >
Text File  |  1993-09-10  |  17KB  |  346 lines
  1. !Virtual 0.37
  2. =============
  3.  
  4. !Virtual supplies virtual memory under RISC OS 2/3, allowing a task to
  5. believe it has upto 24M of memory, yet have a draggable WimpSlot that can be
  6. set as desired. However, it is fairly restrictive in what can be done -
  7. basically only line based (non desktop) programs can be used. This is quite
  8. sufficient to run C compilers, though, which is what we wanted it for. It is
  9. fully compatible with the Acorn DDE development environment.
  10.  
  11. It has been tested on a wide range of machines (ARM2/3, RISC OS 2/3, MEMC
  12. 1/1a, 1/2/4/8MB RAM) so should run on pretty much anything. It will only
  13. work on  machines with 8, 16 or 32Kb page sizes currently (which covers all
  14. Acorn RISC computers at the moment).
  15.  
  16. All RISC OS swi calls run in supervisor mode. On the ARM2/ARM3 a prefetch or
  17. data abort corrupts svc_R14, and RISC OS isn't written to support this. So
  18. it is pretty much of a dead loss to let any swis access virtual memory.
  19. Also, the Wimp is very grungy with its memory mapping, and basically dies if
  20. it sees even the slightest change to the memory map.
  21.  
  22. So !Virtual acts as a replacement for taskwindow, and uses the same
  23. interface to !(Src)Edit for i/o. The task under !Virtual runs with a
  24. virtualised memory map, strictly in user mode. It is preempted from time to
  25. time, to allow the Wimp to continue, but everytime this is done the memory
  26. map has to be put back exactly as the Wimp expects to find it. (Can you say
  27. inefficient?) Any swis that the task tries to issue are intercepted and
  28. "vetted" by !Virtual. Many are treated specially in that certain areas of
  29. memory are forced to be paged in, or large file loads are broken up into
  30. chunks and done page by page with the memory arranged as the Wimp thinks it
  31. should be, in case the filing system expands the RMA. Only swis that
  32. !Virtual understands can be sure of being treated correctly, so any unknown
  33. ones return an error to the application - this means that the task is cut
  34. off from the greater part of RISC OS, and should really be thought of as
  35. running under a different operating system, that just happens to be hosted
  36. on RISC OS.
  37.  
  38. At the moment, only a relatively small number of SWIs have been implemented
  39. (see file 'Bits.SWIs_list') - please contact us if you want a particular SWI
  40. to be supported.
  41.  
  42. How to use:
  43. ==========
  44.  
  45. The module supplies one * command, "*virtual" that is designed as a
  46. replacement for *taskwindow, and accepts a similar set of parameters. Try
  47. "virtual basic -ctrl -discslot 24M" from an obey file, for instance. This
  48. will run basic, which will believe it has 24M at its disposal. (Though if
  49. you don't have that much disk space you had better not use it.) Really, it
  50. only has a WimpSlot the size given by the "Next" Slot, and this can be
  51. dragged up or down in the taskmanager. Notice that the command to be
  52. executed is one parameter, so will have to be quoted if its more than one
  53. word.
  54.  
  55. NOTE! You need a task window 'provider' application loaded to use Virtual.
  56. For instance, !Edit or !SrcEdit. Some other programs provide task window
  57. facilities. eg, Brian's !VMode which gives the user a graphical task window.
  58.  
  59. A new feature for !Virtual is Acorn DDE compatibility - you can setup a
  60. command alias for the 'TaskWindow' command, and all references to
  61. taskwindows will go through !Virtual instead. Hence Ctrl-F12 (on the
  62. TaskManager menu) will start a virtual taskwindow, and !AMU, !CC, !Find,
  63. etc. will all use virtual taskwindows instead of 'real' ones - completely
  64. transparently. All that is required to use this facility is to set ;
  65.  
  66.   *Set Alias$TaskWindow "Virtual %*0"
  67.  
  68. This can be done in the '!Virtual.!Run' file, or in a system !Boot file, or
  69. whatever. To access a 'real' taskwindow, you can either use '*%TaskWindow',
  70. or do a '*UnSet Alias$TaskWindow'.
  71.  
  72. Virtual runs code in one of three states. "Virtual" mode is when the memory
  73. map is changed, special abort handlers are installed, and all user mode swis
  74. with a flat svc stack are redirected. (The flat restriction is because
  75. nfs/econet sometimes drop back into user mode to do work.) "Ext" mode is
  76. used to execute some swis - the memory map is still changed, but no abort
  77. handlers are in place, as they shouldn't happen. Any that do will be caught
  78. by an error handler. OS_WriteC is trapped, so that any output produced can
  79. be redirected to the taskwindow. "Normal" mode is when the memory map is put
  80. back as the Wimp expects, so we can call Wimp_Poll and other things that may
  81. want to rearrange it. OS_WriteC is still trapped, except for the very moment
  82. of Wimp_Poll, and after being in normal mode, I always rescan the memory map
  83. to see if anything has changed.
  84.  
  85. All filing system operations, and most OS_CLIs run in normal mode. If a new
  86. application is started as a result of a command, it is trapped by an upcall
  87. handler, which enters virtual mode with the virtual memory map exactly
  88. matching the application one, and installs lots of vectors. This means that
  89. the WimpSlot must be large enough to *load* the (squeezed) executable of
  90. something that is run.
  91.  
  92. Future: OS_CLIS that start with the character "/", will be specially
  93. treated, to allow the running of executable files that are bigger than the
  94. real WimpSlot that virtual posesses.
  95.  
  96. The *Virtual command allows a task to be run with virtual memory.
  97. Syntax: *Virtual [<command>] [-wimpslot <n>K] [-discslot <n>M]
  98.           [-name <taskname>] [-nice <n>] [-pagefile <filename>]
  99.           [-task <x>] [-txt <x>] [-ctrl] [-display] [-quit]
  100.  
  101.   <command> is the command to be executed
  102.   -wimpslot sets the physical memory to be allocated
  103.   -discslot sets the virtual memory, default 24M
  104.   -name sets the task name
  105.   -nice sets the task priority: 9 low priority, 0 high priority, default 4
  106.   -pagefile sets the swap file for this virtual task - defaults to the
  107.    !SwapDir application
  108.   -task supplies the address of the parent task handle [NOT USER]
  109.   -txt supplies the address of the txt identifier      [NOT USER]
  110.   -ctrl allows control characters through
  111.   -display opens the task window immediately, rather than waiting for a
  112.    character to be printed
  113.   -quit makes the task quit after the command even if the task window has
  114.    been opened
  115.  
  116. Note that fields must be in " " if they comprise more than one word
  117.  
  118. Things to note about the source code:
  119. ====================================
  120.  
  121. Virtual is mostly written in C, with a minimal amount of assembler. It uses
  122. no linked libraries at all. It runs mostly in supervisor mode, but there is
  123. some nefarious switching needed for Wimp_Poll to work.
  124.  
  125. To avoid messing with the supervisor stack, I use R12 as stack pointer in
  126. the C code, and R13 can remain untouched as there's no stack limit. This is
  127. effectively the obsolete APCS_A register allocation. The C compiler is made
  128. to generate assembler source, and the register definitions are then changed
  129. by a sed script.
  130.  
  131. printf is a module written solely to provide a print_f swi so that I can
  132. avoid messing with the C library in the main module, yet produce debug
  133. output easily.
  134.  
  135. Programs running under !Virtual should not be thought of as running under
  136. RISC OS. They have access to a very limited subset of particular SWIs that
  137. I've implemented properly. Further SWI routines accepted with enthusiasm. 
  138.  
  139. Contributors:
  140. ============
  141.  
  142. Many thanks to Ferdinand Oeinck (ferdinan@oeinck.waterland.wlink.nl) for his
  143. continuing work to !Virtual.
  144.  
  145. Reporting problems:
  146. ==================
  147.  
  148. Please read this BEFORE sending me any reports of problems! With a complex
  149. (and buggy!) program like !Virtual, I get a fair few email messages of the
  150. form "I ran your !Virtual, and it didn't work - what am I doing wrong?"
  151.  
  152. PLEASE don't send me such unhelpful comments! Really, I need to know as much
  153. of the following as you can provide in the initial email;
  154.  
  155. * Your machine - model, memory, harddisc (interface), version of RISC OS,
  156.   other hardware or software that may be interfering with !Virtual.
  157. * The application you are running to provide task windows (eg, !edit or
  158.   !srcedit) and which version
  159. * Version number of !Virtual
  160. * Exactly what you did from machine switch on until virtual failed to work
  161.   as expected
  162. * Exactly what happened - eg, did the machine crash completely with the
  163.   mouse pointer stopping ?
  164. * And ideally, the source file and changes required to fix the problem ;-) 
  165.   Obviously if you are not an experienced programmer you can't do this.
  166.  
  167. Distribution:
  168. ============
  169.  
  170. This software may be freely redistributed, so long as only a reasonable
  171. copying or media charge is made, and all files I distribute are included. I
  172. retain copyright to the code. Commercial (including magazine) distribution,
  173. or distributing modified versions of this please contact me - I am normally
  174. happy for it to be reused in other free software, but like to avoid deviant
  175. versions of mine causing trouble.
  176.  
  177. I am not asking for money, but if you like and use it I would be surprised
  178. and amazed by any contributions, and you will receive a disc with latest
  179. versions on. (>£10, say)
  180.  
  181. Brian Brunswick                              brian@aleph1.co.uk (Internet)
  182. Fairview                                  OR Brian.Brunswick@cl.cam.ac.uk          
  183. Avenue des Hirondelles
  184. Pool-in-WharfeDale
  185. Leeds
  186. LS21 1EY
  187. UK
  188. 0532 843737
  189.  
  190. Versions later than 0.20:
  191. ========================
  192.  
  193. Because Brian is now out 'in the real world' I (Nick Smith) am acting as a
  194. first line of support for !Virtual. I have tidied it up for the first public
  195. release, and will improve the program as I get feed back from users, etc.
  196. Currently, Brian wrote 90% of the actual software - so send him all that
  197. money in gratitude !
  198.  
  199. Please email or snail-mail me comments, bug reports, requests for new
  200. features, etc. and I will hopefully have the time to deal with them. If you
  201. make any modifications to the code, please send them to me rather than
  202. giving out copies - I would like to coordinate new releases. Thanks.
  203.  
  204. I can be contacted at the following address, at least until Jul '94 ;
  205.  
  206. N.A. Smith                                    nas20@cus.cam.ac.uk (Internet)
  207. Churchill College
  208. Cambridge
  209. CB3 0DS                 
  210.  
  211. Revision history:
  212. ================
  213.  
  214. Modifications to v0.21 (13-Mar-93) [ß-release]
  215.   - !SwapDir resources application
  216.   - Improved documention; added installation instructions, updated info,
  217.     added revision history, etc
  218.   - removed compilation dependency on having brian's harddrive 8-)
  219.   - did some slightly better (but still awful) !Sprites, with !Sprites22
  220.   - detailed *Help command provided
  221.   - cleaned up code & file structure generally
  222.   - cleaned up test/example software
  223.  
  224. Modifications to v0.22 (14-Mar-93) [release]
  225.   - Made small number of changes that Brian asked for
  226.  
  227. Modifications to v0.23 (12-Apr-93) [release]
  228.   - Bug reports showed that using pseudo-filing system Swap: was not
  229.     RISC OS 2 compatible (really - people still use it!), so some 
  230.     very minor changes to use <Swap$Path>PageFile0 instead of
  231.     Swap:PageFile0
  232.  
  233. Modifications to v0.24 (20-Apr-93)
  234.   - Some more ideas for the 'ToDo' file
  235.   - New SWI provided; Virtual_TaskInfo, like TaskWindow_TaskInfo
  236.   - Some more SWIs supported including OS_Mouse, OS_SWINumberFromString,
  237.     OS_ReadMonotonicTime and TaskWindow_TaskInfo
  238.   - 'Bits.SWIs_list' file created - list of all supported SWIs
  239.   - Better sprites for !SwapDir
  240.   - Started work on !StartTask; a simple FrontEnd application that 
  241.     gives a 'friendly' user interface to the *Virtual command
  242.  
  243. Modifications to v0.25 (29-Jun-93) 
  244.   - Some useful bugfixes/contributed code from Ferdinand Oeinck ;
  245.   - bugfix in MEMC page initialisation, now in FixMemMaps(), so that
  246.     programs called from system() now return correctly. This was the serious
  247.     problem that was stopping the Arc gcc compiler port from working!
  248.   - Wimp_SlotSize SWI is now interpreted better
  249.   - OS_Control, OS_ReadVduVariables, OS_SetVarVal, and OS_ConvertHex8 SWIs
  250.     added
  251.   - It is now possible to start Virtual in the Supervisor mode with the
  252.     command ie 'Virtual "gos" -ctrl -wimpslot 3M'. When a program called
  253.     from the prompt finishes, Virtual will stop, but you can get the prompt
  254.     back by choosing 'Reconnect' from the Taskwindow menu.
  255.   - Escape handling is now implemented, and works *most* of the time.
  256.   - NOTE! This is an 'emergency' release to fix the gcc problems - lots more
  257.     work will be done before the next release, hopefully mid-August.
  258.     Some of the code new to 0.24 hasn't been finished/tested.
  259.  
  260. Modifications to v0.26 (02-Jul-93)
  261.   - Another bugfix release - some more fixes from Ferdinand
  262.  
  263. Modifications to v0.27 (06-Jul-93) [release]
  264.   - Some minor bugfixes, and a new gcc example makefile test for !Virtual
  265.   - MAJOR bugfix for 16Kb pagesize (ie, 2MB RAM machines) *AT LAST* :-)
  266.   - This version sent to Newcastle info-server
  267.  
  268. Modifications to v0.28 (09-Jul-93) 
  269.   - Problem with RISC OS 2 command parameters fixed
  270.   - Now taskwindow compatible. Use *set alias$taskwindow "virtual %*0"
  271.   - Mistake in hires sprites being defined in custom Mode 61 fixed
  272.   - !VDump won't run under RISC OS 2, so now correctly checks the OS when
  273.     loading, and exits cleanly under RISC OS 2.
  274.  
  275. Modifications to v0.29 (21-Jul-93)
  276.   - Sent SWI chunk allocation request to Acorn Customer Support
  277.   - Improved documentation on -pagefile, -txt, -task, -nice and -discslot
  278.     parameters
  279.   - Implemented Virtual_TaskInfo SWI
  280.   - Implemented -discslot, and altered -wimpslot to physical RAM setting
  281.   - Implemented -nice parameter for sceduling, controlling both timeslice,
  282.     and delay to next wimp_pollidle
  283.   - Fixed a problem with command parameters on subsequent OS_GetEnv (may
  284.     have reintroduced RO2 problem :-(
  285.                     
  286. Modifications to v0.30 (22-Jul-93)
  287.   - Implemented DDEUtils_Prefix SWI handler (still broken :-(
  288.   - Added appropriate code to deal with extended command lines from DDE
  289.     FrontEnd tools
  290.   - Added OS_Plot SWI
  291.  
  292. Modifications to v0.31 (23-Jul-93)
  293.   - Finally sorted out !StartTask frontend application by using a 16 byte
  294.     utility to call wimp_starttask on extended command line
  295.  
  296. Modifications to v0.32 (10-Aug-93)
  297.   - Finally fixed problem with DDEUtils_Prefix - thanks Ferdinand!
  298.     now fully compatible with Acorn DDE suite, just enable the *Taskwindow
  299.     alias command in the !Run file and the DDE will use virtual taskwindows
  300.   - Added details of taskwindow alias to !Help file
  301.   - Noticed problem running !StartTask with Alias$TaskWindow set (a virtual
  302.     task cannot be run from inside another virtual task currently) so we
  303.     just ignore any !StartTask commands in this case
  304.  
  305. Modifications to v0.33 (16-Aug-93) [release]
  306.   - New patch for an interesting SWI call ;-) Fixed mistake in xswis.h
  307.   - Continuing problems with command parameters under RISCOS 2. It is
  308.     unlikely that we can fix these in the near future - try getting RO3!
  309.   - Stopped !StartTask from loading under RO2 - again, this won't be
  310.     fixed
  311.   - Saved a bit of memory by compiling virtual with -ff (no embedded
  312.     function names)
  313.  
  314. Modifications to v0.34 (19-Aug-93) 
  315.   - Support added for OS_Byte, 129 call - required for some development s/w
  316.   - Noticed that -quit/display/ctrl flags seem to be ignored completely!
  317.     fixed up -quit so that it at least works(ish)
  318.   - ShellCLI_TaskQuit didn't work (ignored) so built an alias for it so
  319.     it works in both normal and virtual taskwindows
  320.   - Support for Wimp_SendMessage SWI call
  321.  
  322. Modifications to v0.35 (24-Aug-93) 
  323.   - Got Acorn-allocated SWI chunk number :-)
  324.   - Put together some ideas for the planned !Vmonitor application - but
  325.     I'm not writing it!
  326.                       
  327. Modifications to v0.36 (06-Sep-93) 
  328.   - Expanded on ideas for planned !VMonitor application
  329.   - Deleted redundant poll.s and pager.s files from distribution
  330.   - Added OS_File,0 and OS_File,10 SWI handlers, since some versions of
  331.     squeeze (?) seem to require this
  332.   - Added (c) messages to all source files
  333.   - Removed 'Bits' module from inside !Virtual application
  334.   - Pulled out all the #ifdef's for FIXED_SYSTEM_VERSION, TASKWINDOW_,
  335.     etc - the new code works, so I've removed the old code completely
  336.   - bracketed some more debugging messages with *ifdef DEBUG's
  337.  
  338. Modifications to v0.37 (07-Sep-93) [release]
  339.   - Fixed the 'task input' code - not perfect, but works for all normal
  340.     inputs, and doesn't crash
  341.   - Tested on RISCOS 2 machine - text files reformatted for a Mode 12
  342.     screen
  343.   - ReBuilt 'Start' code for !StartTask - now uses new Virtual SWI chunk
  344.   - Made a binaries-only distribution for a wider audience
  345.                          
  346.